Publier une fiche Rzine
Processus de rédaction, soumission et relecture d’une fiche Rzine
1 Une fiche Rzine ?
La “fiche” est le premier format de documentation de la collection Rzine. Il s’agit d’un document didactique qui présente une méthodologie, un type d’analyse, une fonctionnalité, ou encore le traitement d’un certain type de données avec le langage R. Une fiche peut être principalement technique, méthodologique ou thématique, mais elle peut aussi couvrir ces trois aspects. Le premier objectif d’une fiche consiste à partager de manière pédagogique des méthodes reproductibles, applicables en SHS.
La publication de fiche est ouverte à tou·te·s, quelque soit son statut et sa discipline. Une fiche peut être réalisée à plusieurs et présenter une dimension interdisciplinaire.
Les auteur·e·s sont libres dans le choix de la problématique et dans la façon d’articuler le contenu. Il est cependant indispensable que le contenu d’une fiche soit correctement contextualisé et qu’il soit intelligible par l’ensemble des disciplines de SHS. Il est également obligatoire de suivre les règles suivantes :
- Utiliser le modèle de mise en page
readrzine - Rédiger en français ou en anglais
- Introduire et contextualiser le contenu
- Présenter du code entièrement reproductible
- Utiliser des données libres d’utilisation et mises à disposition des lecteurs
- Fournir des fichiers et annexes associés
Vous pouvez consulter les premières fiches déjà produites pour vous faire une idée du résultat attendu :
- Analyse Territoriale Multiscalaire, Ronan Ysebaert et Claude Grasland.
- Analyse des corrélations avec easystats, Grégoire Le Campion.
- Exploration spatio-temporelle d’objets géographiques ponctuels, Marion Le Texier.
- Réaliser une carte de discontinuités en 2,5D, Nicolas Lambert.
Rzine souhaite promouvoir l’usage de logiciels contribuant à une science plus ouverte et reproductible, et participer à une montée en compétence des disciplines de SHS dans ce domaine. C’est pour cela que l’ensemble du processus d’évaluation se déroule sur GitHub (service web d’hébergement et de gestion de développement de logiciels) qui repose sur le logiciel de gestion de versions Git.
1.1 Critères d’acceptation
Afin d’assurer la cohérence de la collection et une certaine qualité du contenu des fiches Rzine, plusieurs critères d’acceptation ont été établis. Certains de ces critères sont soumis à un ou plusieurs évaluateur·rice·s, d’autres peuvent faire l’objet d’un refus immédiat de la part des éditeur·rice·s du comité de lecture.
Les éditeur·rice·s et les évaluateur·rice·s veilleront à ce que la démonstration soit contextualisée (champ disciplinaire d’application, enjeux en terme de reproductibilité…) et rigoureuse. Le code présenté se doit d’être lisible, commenté et reproductible. Les packages mobilisés doivent être brièvement décrits et leur utilisation justifiée. Enfin, les données utilisées dans le cadre de la démonstration doivent obligatoirement être sourcées, libres de droit et mises à disposition.
| Critères d’évaluations d’une fiche | Editeur·rice·s | Evaluateur·rice·s |
|---|---|---|
| Respect des consignes éditoriales (partie 4) | X | |
| Acceptation des futures conditions d’utilisation CC BY-SA 4.0 | X | |
| Pas de fiche Rzine similaire déjà produite* | X | |
| N’a pas fait l’objet d’une publication par ailleurs | X | |
| Pas de renvoi publicitaire explicite | X | X |
| Respect du Règlement Général sur la Protection des Données | X | X |
| Intérêt pour la communauté des utilisateurs de R en SHS | X | X |
| Données utilisées libres, sourcées et mises à disposition (partie 4.2) | X | X |
| Rédaction dans un français ou un anglais correct | X | |
| Concerne des méthodes applicables en SHS (et sciences territoriales) | X | |
| Contextualisation de l’analyse ou méthode présentée | X | |
| Présentation des prérequis techniques et méthodologiques | X | |
| Clarté et rigueur de la ressource et de la démonstration | X | |
| Clarté (indentation, commentaire…) et reproductibilité du code présenté | X | X |
| Justification (et stabilité) des packages utilisés | X | X |
*Le cas échéant, le comité de lecture se réserve la possibilité de mettre en relation différents contributeur.rice.s pour leur proposer la rédaction collaborative d’une fiche.
1.2 Format et template
Une fiche Rzine est document computationnel, alternant du texte et du code (programmation lettrée). Il s’agit d’un fichier HTML produit en R Markdown. Il se construit avec R et repose sur les packages rmarkdown et knitr.
Le modèle de mise en page est mis à disposition via le package rzine. Son installation ainsi que la création d’une fiche Rzine vierge sont expliqués dans la partie 2.
1.3 Soumission et évaluation
L’ensemble du processus de soumission et d’évaluation d’une fiche se déroule sur GitHub. Cela facilite la gestion de version, permet l’archivage et la transparence de l’évaluation d’une fiche.
Pour être soumise à évaluation, une fiche doit être déposée et déployée sur GitHub (cf. partie 5).
Dans le cas où l’ensemble des critères d’acceptations sont respectés, le comité de lecture désigne un éditeur.rice référent qui coordonnera tout le processus d’évaluation et de publication. Il propose également deux évaluateur·rice·s à l’auteur·e. Une fois le processus d’évaluation enclenché, les retours (publics) des évaluateur·rice·s et de l’éditeur·rice se font directement sur GitHub (cf. partie 6).
1.4 Publication et licence d’utilisation
Une fois le processus d’évaluation terminée, les éditeur·rice·s du comité de lecture s’occupent de la mise en page finale de la fiche, du dépôt d’un DOI, du référencement du document sur HAL et de sa mise en ligne sur le site rzine.fr.
Le projet Rzine souhaite promouvoir les pratiques contribuant à une science plus ouverte et reproductible. C’est pour cette raison que l’ensemble des publications de la collection Rzine, ainsi que leurs codes sources, sont automatiquement mis à disposition de tou·te·s et libres de droit.
Etre auteur.e d’une fiche Rzine, c’est accepter à ce que votre publication soit mise à disposition sous les conditions d’utilisation de la licence Creative Commons BY-SA 4.0 et que son code source réponde aux condition d’utilisation de la licence…
Afin d’éviter tout malentendu avec les auteur·e·s, la signature d’un accord de principe sera demandé.2 Le package rzine
Le package Rzine fournit le modèle de mise en page des fiches Rzine, ainsi que l’architecture de répertoire et l’ensemble des fichiers associés à fournir.
2.1 Installation du package rzine
Le package est mis à disposition sur un depôt de l’organisation Rzine sur l’instance GitLab de la TGIR Huma-num. Pour l’installer et le charger, exécutez les lignes suivantes :
# install.packages(remotes)
remotes::install_gitlab("rzine/package", host = "https://gitlab.huma-num.fr/", force = TRUE)
library(rzine)2.2 Utiliser le template readrzine
Avant de générer une fiche Rzine vierge, il est important de spécifier un répertoire de travail. Pour cela, deux solutions s’offrent à vous :
1- La solution standart
Créez un répertoire sur votre ordinateur, et spécifiez-le comme répertoire de travail avec la fonction setwd(), exemple :
setwd("/home/jeanne/Documents/Fiche_rzine")2- La solution Rstudio (recommandée)
Créez un projet Rstudio. Pour cela, cliquez sur File/New Project, sélectionnez New Directory, puis New Project :
2.2.1 Générer une fiche vierge (.Rmd)
Une fois dans votre votre projet Rstudio (ou que vous avez spécifié votre répertoire de travail de manière standart), vous pouvez générer une fiche readrzine vierge en ligne de commande. Pour cela, copiez-collez les lignes de code suivantes sans les modifier, puis exécutez :
rmarkdown::draft(file = "index.Rmd",
template = "readrzine",
package = "rzine",
create_dir = FALSE,
edit = FALSE)Cela génère un ensemble de fichiers à la racine de votre répertoire de travail. Certains fichiers sont à modifier ou à ajouter en fonction du contenu de votre fiche :
2.3 Kniter la fiche (.html)
Le fichier le plus important est index.Rmd. Il s’agit du fichier R Markdown source à partir duquel sera généré la fiche Rzine en format HTML. Ne modifiez pas son nom.
Pour générer le document en format HTML, il suffit de kniter (tricoter) ce fichier. Cela revient à le convertir dans un premier temps en format markdown puis (dans ce cas) en format HTML via Pandoc (logiciel libre de conversion de documents).
Vous pouvez kniter (générer) le R Markdown readrzine en format HMTL de différente manière :
1- En ligne de code
Copiez-collez ces lignes de commande puis exécutez pour générer le fichier HTML :
rmarkdown::render("index.Rmd", envir = new.env())2- En clic- bouton avec Rstudio
Ou cliquez tout simplement sur knit depuis l’interface Rstudio :
3- Raccourci clavier
Vous pouvez également utiliser le raccourci clavier suivant : CTRL+SHIFT+K
Cela engendre la création d’un fichier du même nom mais en format HTML (index.html) à la racine de votre répertoire. Il s’agit du fichier index.Rmd mis en page à partir du modèle readrzine.
Voici à quoi ressemble une fiche Rzine vierge knité :
3 Anatomie d’un R Markdown
Bien que dans le cadre d’une publication Rzine certaines métadonnées et informations sont à renseigner et que certaines règles de mise en page doivent également être appliquées, le modèle de mise en page readrzine fonctionne comme n’importe quel fichier R Markdown.
Cette partie présente très brièvement les grandes composantes d’un fichier R markdown.
3.1 L’en-tête
L’en-tête d’un document R Markdown (parfois appelé YAML header) est délimité par deux lignes de trois tirets et contient des métadonnées et les éléments de style du document. Voici à quoi ressemble l’en-tête vierge du template readrzine :
---
title: "Titre fiche"
subtitle: "Sous-titre fiche"
date: "`r Sys.Date()`"
author:
- name: Premier Auteur.e
affiliation: Affiliation_1, Affiliation_2
- name: Second Auteur.e
affiliation: Affiliation_1, Affiliation_2
image: "featured.png"
logo: "figures/rzine.png"
output:
rzine::readrzine:
highlight: kate
number_sections: true
csl: Rzine_citation.csl
bibliography: biblio.bib
nocite: |
@*
link-citations: true
# github: "author/repository"
# gitlab: "gitlab.huma-num.fr/author/repository"
# doi: "xx.xxx/xxxx.xxxxxxx"
# licence: "by-sa"
# Only Creative Commons Licence
# 5 possible choices : "by-nd", "by", "by-nc-sa", "by-nc","by-sa"
---3.2 Le texte balisé en markdown
Le corps d’un document R Markdown comprend deux types de contenu, que l’on peut librement alterner :
- Des blocs de texte brut mis en forme selon la syntaxe markdown;
- Des blocs de code, appelés chunks (cf partie 3.3).
Le corps du document est constitué de texte mis en forme à l’aide de la syntaxe Markdown. Le markdown est un langage de balisage léger et très facile à maîtriser, qui permet de définir des niveaux de titres ou de mettre en forme le texte.
Par exemple, le texte suivant :
Ceci est du texte en *italique*, **gras** ou en ***gras italique***.
Pour définir des listes à puces, utilisez les **tirets** :
- premier élément
- second élément
Vous pouvez également ajouter des [liens cliquables](https://rzine.fr/)
Se formalisera de la manière suivante dans le fichier HTML généré :
Ceci est du texte en italique, gras ou en Gras italique.
Pour définir des listes à puces, utilisez les tirets :
- premier élément
- deuxième élément
Ou encore ajouter des liens cliquables.
3.3 Les chunks
En plus du texte libre balisé en markdown, un document R Markdown peut évidemment contenir du code R.
Celui-ci doit être inclus dans des chunks délimités par la syntaxe suivante :
```{r}
x <- 37 + 12
print(x)
```
Pour insérer facilement un nouveau chunk, vous pouvez utiliser le menu Insert proposé par l’IDE RStudio, situé en haut à droite de l’éditeur de texte (à gauche du bouton Run) :
Vous pouvez également utiliser le raccourci clavier Ctrl+Alt+i pour générer un chunk vide.
Il est possible donner un nom (unique) à chaque chunk, de la façon suivante :
```{r nom_du_chunck}
```
Il n’est pas obligatoire de nommer un chunk, mais cela peut être utile pour localiser une erreur lors de la compilation du code.
Un certain nombre d’options peuvent également être ajoutées sous la forme option = valeur. Exemple :
```{r nom_du_chunck, echo = FALSE, warning = FALSE}
x <- 37 + 12
print(x)
```
L’option echo permet d’afficher, ou non, le code dans le document généré. L’option warning permet d’afficher ou non les warnings générés par le code en sortie. Voici la liste des principales options disponibles :
| Option | Valeurs | Description |
|---|---|---|
| echo | TRUE/FALSE | Afficher ou non le code R dans le document en sortie |
| eval | TRUE/FALSE | Exécuter ou non le code R durant la compilation du Rmarkdown |
| include | TRUE/FALSE | Inclure ou non le code R et ses résultats dans le document |
| warning | TRUE/FALSE | Afficher ou non les avertissements générés par le code du chunk |
| message | TRUE/FALSE | Afficher ou non les messages générés par le code du chunk |
L’ensemble des options disponibles sont décrites dans le guide de référence R Markdown, et également dans plusieurs références listées ci-dessous.
3.4 Documentation de référence
Pour en savoir plus et se former au R Markdown et à la syntaxe markdown :
- Cookbook R Markdown, de Y. Xie, C. Dervieux & E. Riederer
- R Markdown Definitive Guide, de Y. Xie, J. J. Allaire & G. Grolemund
- R Markdown for Scientists, de Nicholas Tierney
- Introduction à R et au tidyverse, de Julien Barnier
- Travail collaboratif avec R, de Lino Galiana
- Pimp my RMD: a few tips for R Markdown, de Yan Holtz
- R for Data Science, de H. Wickham & G. Groelemund
- Guide de la syntaxe R Markdown, de Rstudio
- guide de référence R Markdown, de Rstudio
- R Markdown Cheatsheet, de Rstudio
- Writing Reproducible Research Papers with R Markdown, de Resul Umit
4 La rédaction d’une fiche
Les auteur.e.s sont libres dans le choix de la problématique et dans la façon d’articuler le contenu de leur fiche Rzine, mais afin d’assurer une certaine cohérence éditoriale et une qualité du contenu de la collection, les auteur.e.s sont soumis à quelques obligations dans l’organisation du contenu.
4.1 Métadonnées d’une fiche
Commencez par personnaliser l’en-tête du template readrzine (YAML header), en modifiant le titre, le sous-titre, le.s nom.s de ou des auteur.es et les affiliations, exemple :
---
title: "Analyse textuelle exploratoire"
subtitle: "Exploration d'un corpus de lettre avec les package Quanteda"
date: "`r Sys.Date()`"
author:
- name: Jeanne Dupont
affiliation: UMR TEXTO, CNRS
- name: Second Paul Edouard
affiliation: Centre documentaire ED, Université de France4.2 Contextualisation du contenu
Une fiche doit obligatoirement contenir une introduction, qui explicite l’objectif, le contenu et les données utilisés. Si nécessaire, il est également demandé au auteure.s de contextualiser le contenu, autant sur le plan thématique que technique. N’hésitez-pas à ajouter des références dans la bibliographie.
Une fiche Rzine doit s’adresser à l’ensemble des disciplines de SHS et des sciences territoriales. Considérez que vos lecteur.rice.s ne seront pas forcément des spécialistes de la thématique ou méthode présentée !
4.3 Données utilisées
L’intégralité des données utilisées pour une fiche doivent :
- Être présentées et décrites dans la fiche.
- Être libre d’utilisation et de diffusion.
- Être mises à disposition des lecteur.rice.s, même si ces données sont déjà en libre accès.
- Être associées à des métadonnées qui permettent de retracer et comprendre ces données.
- Respecter le Règlement Général sur la Protection des Données.
Toutes les données chargées et utilisées dans une fiche devront être stockées dans le répertoire :
Chaque fichier de données ajouté doit être associé à un fichier de métadonnées !
4.4 Packages utilisés
4.5 Image d’illustration et figures
4.5.1 Illustration de couverture
Le template readrzine permet l’affichage d’une illustration en couverture :
Cela n’est pas obligatoire. Si vous ne souhaitez pas d’image de couverture, supprimez tout simplement la métadonnée concernée dans l’en-tête du R Markdown :
Sinon, pour modifier l’illustration par défaut, il suffit de remplacer l’image nommée featured.png à la racine du répertoire par celle de votre choix (le nom doit être identique !) :
Pour un rendu correct, le format attendu de cette image de couverture est de type ‘bandeau’ (ex : 750 x 300). N’hésitez pas à contacter le comité éditorial si vous ne maîtrisez pas cet aspect : contact@rzine.fr.
4.5.2 Image dans le corps du texte
Les illustrations affichées dans le corps d’une fiche doivent être stockées dans le répertoire “figures”.
Il est recommandé de les insérer dans votre markdown en utilisant un chunk de code R, et non la syntaxe markdown ou des balises HTML !
Par exemple, ce chunk…
```{r, echo=FALSE, fig.align='center', out.width = "15%"}
include_graphics("figures/folder_figures.png")
```
… Permet d’afficher l’image “folder_figures.png” centrée et représentant 15% de la largeur du document. Ex :
Plusieurs options sont disponibles pour paramétrer l’image affichée. Vous pouvez les consulter dans le guide de référence R Markdown de Rstudio.
4.6 Formules mathématiques
Il est possible d’écrire des formules mathématiques en langage \(\TeX\). Pour cela, il suffit de délimiter le contenu \(\LaTeX\) par un ou deux symboles $, ex :
$$ y = \sqrt{\frac{1}{x + \beta}} $$
En mode Inline (un seul $) , les formules sont incluses à l’intérieur du paragraphe courant, ex : \(\sum_{i=1}^n X_i\)
En mode Displayed (deux $), elles apparaissent centrées et mises en exergue, ex : \[ y = \sqrt{\frac{1}{x + \beta}} \]
Sur le Web, vous trouverez beaucoup de documentation sur le langage de balisage markdown. Quelques références sont listées dans la partie 3.4
4.7 Ecriture de code R
4.8 Message d’alerte
4.9 Références bibliographiques
Bien qu’il ne s’agisse pas d’une obligation, le template readrzine intègre automatiquement cette section. Si vous ne souhaitez pas afficher de bibliographie dans votre fiche, vous pouvez supprimer les lignes suivantes de votre R Markdown :
# Bibliographie {-}
<div id="refs"></div>
Si cette section vous intéresse, ne modifiez pas ces lignes. Il vous suffira de modifier/compléter les différentes références bibliographiques que vous souhaitez utiliser dans le fichier “biblio.bib” (format BibTeX), situé à la racine du répertoire :
Le template par défaut du fichier biblio.bib :
@Manual{R-base,
title = {R: A Language and Environment for Statistical Computing},
author = {{R Core Team}},
organization = {R Foundation for Statistical Computing},
address = {Vienna, Austria},
year = {2020},
url = {https://www.R-project.org/},
}
@Manual{R-knitr,
title = {knitr: A General-Purpose Package for Dynamic Report Generation in R},
author = {Yihui Xie},
year = {2020},
note = {R package version 1.28},
url = {https://CRAN.R-project.org/package=knitr},
}
@Manual{R-rmdformats,
title = {rmdformats: HTML Output Formats and Templates for 'rmarkdown' Documents},
author = {Julien Barnier},
year = {2021},
note = {R package version 1.0.2},
url = {https://github.com/juba/rmdformats},
}
Pour citer une références dans le corps du texte, utilisez la syntaxe suivante : [@Citation Key].
Par exemple [@R-base] affichera (R Core Team 2020) dans le corps du document.
Toutes les références bibliographiques présentes dans le fichier biblio.bib seront automatiquement ajoutées dans la section “Bibliographie”.
4.10 Glossaire
Cette section n’est pas obligatoire, cependant vos lecteur.rices ne seront pas forcément issus de votre discipline ou ne maîtriseront peut-être pas la thématique et/ou méthode présentée. Pour que l’ensemble de la démonstration soit compréhensible par un public large, vous pouvez utiliser la section “glossaire” pour définir certains termes utilisés dans la fiche.
Pour cela, il suffit d’utiliser la syntaxe markdown suivante dans le corps du texte :
Blabla bla bla bla bla mot à définir^[__Mot à définir__: Définition du terme... ect]
Au knit du document en format HTML, un numéro est associé et affiché après le “mot à définir”. Et ce mot et sa définition seront ajoutés dans la section glossaire.
Exemple : Mot à définir1
Un lien interactif est alors automatiquement crée entre le “mot” dans le corps du texte et sa définition dans la section “Glossaire”.
Si vous ne souhaitez pas utilisez de “Glossaire”, vous pouvez supprimer ces lignes du template readrzine :
## Glossaire {- #endnotes}
<script type="text/javascript">
$(document).ready(function() {
$('.footnotes ol').appendTo('#endnotes');
$('.footnotes').remove();
});
</script>
4.11 Fichier readme.md
4.12 Annexes obligatoires
4.12.1 Informations sur la session
Cette section obligatoire est directement intégrée au template :
## Infos session {-}
```{r session_info, echo=FALSE}
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[1]], row.names = F))
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[2]], row.names = F))
```
Ne modifiez et ne déplacez pas cette section. Il s’agit de la première partie obligatoire des annexes.
Ce bout de code affiche des informations sur la session qui a permis de générer cette fiche (système d’exploitation, version de R et des packages utilisés). Voir l’exemple pour ce document.
4.12.2 Citation du document
Cette section obligatoire est directement intégrée au template :
## Citation {-}
```{r Citation, echo=FALSE}
rref <- bibentry(
bibtype = "article",
title = "Titre de la fiche",
author = person("Auteur.e 1", "Auteur.e 2" ),
journal = "Rzine.fr",
publisher = "FR CIST",
year = 2021,
url = "https://...")
```
`r capture.output(print(rref))`
### BibTex : {-}
```{r generateBibTex, echo=FALSE}
writeLines(toBibtex(rref), "cite.bib")
toBibtex(rref)
```
<br/>
Ces deux chunks permettent l’affichage de la référence bibliographique de votre fiche dans le corps du document (Voir l’exemple pour ce document), ainsi que le stockage de cette référence en format BibTex, enregistrée dans le fichier cite.bib à la racine du répertoire.
Ne mofifiez pas cette section. Elle sera complétée avant publication par l’équipe éditoriale.
5 La soumission d’une fiche
Une fois que la rédaction de votre fiche est terminée, c’est à dire que :
- Le fichier index.Rmd est rédigé.
- Le fichier index.Rmd a été compilé en format HTML (knit).
- L’ensemble des fichiers annexes (biblio.bib et featured.png) ont été complétés ou remplacés.
- Les répertoires “figures” et “data” ont été remplis par les fichiers attendus
Vous pouvez soumettre votre fiche au comité éditorial Rzine !
Une fois votre fiche rédigée, vous devriez être en possession d’un répertoire contenant les fichiers et sous-répertoires suivants. Comme indiqué dans la documentation, les fichiers biblio.bib et featured.png ne sont pas obligatoires :
Vous êtes alors en mesure de soumettre votre travail au comité de lecture Rzine. Pour cela, vous devez :
- Déposer votre travail sur un dépôt Git (logiciel de gestion de versions décentralisé).
- Déployer la fiche en format HTML depuis le dépôt Git pour la rendre consultable en ligne.
- Contacter le comité de lecture en lui fournissant l’adresse du dépôt.
Ne soyez pas inquiet si vous n’avez aucune connaissance de Git, ce document détaille clairement toutes les étapes à réaliser. Profitez-en pour vous former à cet outil puissant qui change la vie !
5.1 Premiers pas sur Github
Le logiciel de gestion de versions décentralisé à utiliser pour la soumission est le plus connu et le plus utilisé dans le monde : GitHub. La première chose à faire est donc de vous créer un compte.
5.1.1 Création de compte
Connectez-vous à la page de création de compte GitHub.
Saisissez le courriel que vous souhaitez utiliser, un mot de passe, un nom d’utilisateur et répondez aux questions de sécurité pour créer votre compte. Un code de sécurité vous sera envoyé au courriel renseigné afin de valider la création du compte…
5.1.2 Création d’un dépôt
Vous avez désormais un compte GitHub :
Cliquez sur “Start a project” ou “Create repository” pour créer un dépôt qui hébergera votre fiche.
Vous pouvez également créer un nouveau dépôt en cliquant sur “+” puis “New repository” en haut à droite de la fenêtre :
Un fois sur la page de création d’un nouveau dépôt, saisissez un nom de dépôt (sans espaces ni caractères spéciaux) et éventuellement une description. Initialisez ce dépôt comme Public et demandez l’ajout automatique d’un fichier README.md :
Puis cliquez sur “Create repository”. Votre dépôt, uniquement rempli d’un fichier README.md, a été créé :
5.2 Remplissage du dépôt
Vous pouvez désormais y ajouter le répertoire contenant tous les fichiers (et sous-répertoires) de votre Fiche.
Il existe plusieurs méthodes pour téléverser des fichiers sur GitHub (en ligne de commande ou en clic-bouton). Nous présentons ici la méthode clic-bouton depuis l’interface de GitHub.
Pour cela, cliquez sur “Add file”, puis sur “Upload files” :.
Faîtes glisser l’ensemble des fichiers et sous-répertoires de votre fiche dans le dépôt :
Ajoutez un commentaire et cliquez sur “Commit changes” :
Vous venez de réaliser votre premier “commit” (enregistrement des changements). L’ensemble des fichiers sont désormais stockés sur le dépôt :
Ce dépôt étant paramétré comme Public, tout le monde peut désormais consulter et récupérer ces fichiers.
5.3 Déploiement de la fiche
Les fichiers sont consultables à l’état brut, mais une manipulation supplémentaire va permettre de mettre en ligne votre fiche (format HTML). Votre fiche mise en page sera ainsi consultable par tout le monde sur le web, sans avoir à gérer un serveur ou un site web. C’est trais utile, et très facile à faire !
5.3.1 GitHub Page
Cliquez sur “Settings > Pages > Source (none)” et sélectionnez la branche “main” :
Ne modifiez pas le répertoire ciblé par défaut (”root”) qui indique la racine du dépôt. Cliquez sur “save” :
Félicitations ! Votre fiche est désormais consultable en ligne depuis votre compte GitHub !
La page html est alors distribuée à l’adresse suivante : https://username.gitub.io/repository_name/.
Vous pouvez retrouver l’URL d’accès dans le menu “Settings > Pages” :
Cliquez sur le lien affiché pour consulter la fiche mise en ligne :
5.3.2 README.md
Le fichier markdown “README” est utilisé pour présenter les informations importantes à propos du dépôt. Son contenu est automatiquement affiché (et mise en forme grâce à la syntaxe markdown) en dessous des fichiers listés du dépôt.
Vous pouvez éditer et modifier facilement ce fichier depuis l’interface GitHub en cliquant sur le symbole crayon :
Vous pouvez alors personnalisez le fichier en modifiant : le titre, le sous-titre, le.s auteur.e.s (et affiliation.s), ainsi que l’URL de consultation de la fiche. Exemple :
Une fois les modifications terminées, commentez votre commit, puis cliquez sur Commit changes pour enregistrer les changements effectués :
Et voilà ! vous avez terminé la mise en ligne de votre fiche. Désormais, un lien vers votre fiche déployée est affiché à la racine du dépôt grâce au fichier “README.md” :
5.4 Contacter comité de lecture
Il ne vous reste plus qu’à contacter le comité de lecture Rzine pour soumettre votre fiche à évaluation. Pour cela, envoyez un courriel à contact@rzine.fr, en précisant l’adresse du dépôt qui héberge votre fiche.
Vous serez contacté par le comité de lecture dans les 15 jours suivants l’envoi de ce courriel.
6 Le processus de relecture
L’intégralité du processus de relecture se fera sur GitHub par l’intermédiaire d’issues (voir de Pull-request pour les auteur.e.s les plus à l’aise avec Git).
Cela ne doit pas vous inquiéter… Comme pour l’étape de soumission, vous trouverez l’ensemble des explications et du processus à suivre dans ce document dédié.
En cas de soumission validée, un relecteur·rice doté·e des connaissances techniques et thématiques nécessaires sera proposé·e à l’auteur·e dans les 15 jours.
Rzine est dans une démarche volontariste d’Open Science. La relecture des fiches Rzine est ouverte et transparente. L’identité du ou des relecteur·rice·s et l’ensemble de leurs retours sont publics.
Parce qu’une fiche est un document computationnel, l’ensemble du processus se déroule sur GitHub. Vous serez donc invité·e à ouvrir les droits du dépôt GitHub de votre fiche au relecteur·rice désigné·e. Les retours et les demandes d’améliorations se feront directement sur la plateforme GitHub via des issues et des pull-request.
Une documentation complète est mise à votre disposition ici, pour vous accompagner dans le processus de relecture. Les éditeurs du comité de lecture pourront également vous assister dans ce processus.
7 Le processus éditorial
7.1 Mise en page finale
7.2 Attribution d’un DOI
En cas de publication, un DOI (Digital Object Identifier) sera attribué à chaque fiche par le biais de l’Institut de l’information scientifique et technique du CNRS (INIST).
Le DOI (et le lien vers la page des métadonnées) sera ajouté sur le document par le comité éditorial :
7.3 Dépôt sur HAL
7.4 Mise en ligne de la fiche
Un fois le processus de publication terminé, la fiche sera accessible à tout le monde depuis son dépôt Git. Pour une meilleure visibilité, elle sera également référencée et mise en valeur sur le site rzine.fr :
8 Question ?
Pour toute question relative au processus de soumission et de relecture d’une fiche, vous pouvez contacter le comité éditorial en envoyant un courriel à l’adresse contact@rzine.fr
Bibliographie
Annexes
Info session
| setting | value |
|---|---|
| version | R version 4.1.1 (2021-08-10) |
| os | Windows 10 x64 |
| system | x86_64, mingw32 |
| ui | RTerm |
| language | (EN) |
| collate | French_France.1252 |
| ctype | French_France.1252 |
| tz | Europe/Paris |
| date | 2022-01-07 |
| package | ondiskversion | source |
|---|---|---|
Citation
Rzine Cé (2021). “Publier une fiche Rzine.” doi: 10.48645/xxxxxx (URL:, https://doi.org/10.48645/xxxxxx), <URL:, https://rzine.fr/publication_rzine/xxxxxxx/>.
BibTex :
@Misc{,
title = {Publier une fiche Rzine},
subtitle = {Processus de rédaction, soumission et relecture d’une fiche Rzine},
author = {Comité éditorial Rzine},
doi = {10.48645/xxxxxx},
url = {https://rzine.fr/publication_rzine/xxxxxxx/},
keywords = {FOS: Other social sciences},
language = {fr},
publisher = {FR2007 CIST},
year = {2021},
copyright = {Creative Commons Attribution Share Alike 4.0 International},
}
Glossaire
Mot à définir: Définition du terme à définir… ect.↩︎